Edit

UCX objects and handles used by a host controller driver

  • Article

UCX extends the WDF object functionality to define its own USB-specific UCX objects. UCX uses these objects for queuing requests to any underlying host controller driver.

Summary

  • UCX objects are used by the host controller driver to handle operations related to the controller, its root hub, and all endpoints.
  • UCX objects are created by the host controller driver and each object's lifetime is managed by UCX.

Important APIs

UCX extends the WDF object functionality to define its own USB-specific UCX objects. UCX uses these objects for queuing requests to any underlying host controller driver.

For more details on WDF objects, see Introduction to Framework Objects.

UCXCONTROLLER: Host controller object

Represents the host controller that is created by the host controller driver. The driver must create only one host controller object per host controller instance. Typically created within the EvtDriverDeviceAdd callback by calling the UcxControllerCreate method.

When the host controller driver creates the object, the driver registers its implementation of callback functions that are invoked by UCX. The driver should additionally identify the bus type over which the host controller is connected, such as ACPI or PCI. The driver also provides host controller device information by using the UCX_CONTROLLER_CONFIG structure that is passed to the UcxControllerCreate call.

To handle I/O requests, the host controller driver must register a GUID_DEVINTERFACE_USB_HOST_CONTROLLER device interface. The driver is not required to implement the IOCTLs defined in this interface. Instead, the UCX client passes the IOCTL requests received on this interface to UCX by calling UcxIoDeviceControl.

Here are the callback functions associated with the host controller object, which are invoked by UCX. These functions must be implemented by the host controller driver.

*EVT_UCX_CONTROLLER_USBDEVICE_ADD
Called when the hub driver has determined, via interaction with the root hub and/or external hub(s), that a new device is present on the bus.

*EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY
Called by UCX to gather information about various features supported by USB host controllers.

*EVT_UCX_CONTROLLER_RESET
Called by UCX to reset the controller hardware, possibly in response to a detected error.

*EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER
Used to retrieve the current frame number from the host controller, which is used by the hub driver for scheduling isochronous transfers.

UCXROOTHUB: Root hub object

Gets and controls the status of the root ports of the host controller. Created by the host controller driver typically within the EvtDriverDeviceAdd callback by calling the UcxRootHubCreate method after the host controller object is created. There should be only one root hub object per host controller instance. In the UcxRootHubCreate call, the driver registers its callback implementations.

EVT_UCX_ROOTHUB_GET_INFO
Returns the number of USB 2.0 and USB 3.0 ports of the root hub.

EVT_UCX_ROOTHUB_GET_20PORT_INFO
Return information about the USB 2.0 or USB 3.0 ports (*EVT_UCX_ROOTHUB_GET_30PORT_INFO) of the root hub.

After the root hub object is created and initialized, the hub driver interacts with the root hub ports by sending interrupt and control transfers. UCX assists with these transfers by invoking these callback functions implemented by the host controller driver.

EVT_UCX_ROOTHUB_CONTROL_URB
Handles feature control requests by the USB hub.

EVT_UCX_ROOTHUB_INTERRUPT_TX
Handles request for information about changed ports.

For more information, see Root hub callback functions of a host controller driver.

UCXUSBDEVICE: USB device object

Represents a physical USB device connected to the bus. Created by the host controller driver typically within the EVT_UCX_CONTROLLER_USBDEVICE_ADD callback by calling the UcxUsbDeviceCreate method.

When the object is created, the host controller driver registers its implementation of the callback functions with the UcxUsbDeviceCreate call.

These callback functions are meant to keep the controller and driver informed about the current status of USB devices.

EVT_UCX_USBDEVICE_ENABLE
Prepares the controller for performing transfers to the device's default endpoint.

EVT_UCX_USBDEVICE_DISABLE
Releases controller resources associated with the device and its default endpoint.

EVT_UCX_USBDEVICE_ADDRESS
Programs an address into the controller and sends a SET_ADDRESS transfer to the device, to bring it to the addressed state.

EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE
Programs non-default endpoints into the controller, and/or releases other non-default endpoints.

EVT_UCX_USBDEVICE_RESET
A controller notification that a device has been reset, in which case the driver takes any necessary action to sync the controller with the USB device.

EVT_UCX_USBDEVICE_UPDATE
Notifies the controller of various bits of information related to the device.

EVT_UCX_USBDEVICE_HUB_INFO
A notification about hub properties, if the UCXUSBDEVICE handle is for a hub device.

EVT_UCX_USBDEVICE_ENDPOINT_ADD
Notifies the driver to create an endpoint for the device. EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD for default endpoint.

When an interface on a suspended USB 3.0 device has signaled wake up, the driver is expected to call UcxUsbDeviceRemoteWakeNotification to notify UCX.

After the object is created, the lifetime of the object is managed by UCX, and the driver must not delete the object.

UCXENDPOINT: Endpoint object

Represents an endpoint on a USB device object. Endpoint objects are created by the host controller during either an EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD or an EVT_UCX_USBDEVICE_ENDPOINT_ADD callback. When a endpoint object is created, the driver registers its callback functions.

The driver also creates a framework queue object for each endpoint, and passes the WDFQUEUE for that queue to UCX by calling UcxEndpointSetWdfIoQueue. After the endpoint is created, the lifetime of the object and its associated queues is managed by UCX, and the driver must not delete these objects itself.

The endpoint object implements several callback functions that allow the driver to assist UCX with operations related to the endpoint.

EVT_UCX_ENDPOINT_ABORT
Abort the queue associated with the endpoint.

EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS
Notify the controller driver that it can complete cancelled transfers on the endpoint.

EVT_UCX_ENDPOINT_PURGE
Complete all outstanding I/O requests on the endpoint.

EVT_UCX_ENDPOINT_START
Start the queue associated with the endpoint.

EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD
Create static streams.

EVT_UCX_ENDPOINT_RESET
Notify the driver to reset the controller's programming of the endpoint.

When the host controller driver receives a USB 3.0 No Ping Response Error on an endpoint, the driver must call UcxEndpointNoPingResponseError. That call results in the USB device object receiving EVT_UCX_USBDEVICE_UPDATE. For more information, see Configuring USB endpoints in a host controller driver.

UCXSTREAMS: Stream object

Represents a number of pipes to the device across a single endpoint. The host controller driver creates stream objects in the EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD callback by calling UcxStaticStreamsCreate.

During the UcxStaticStreamsCreate call, the host controller driver registers its callback functions. For a specific endpoint object, the driver can determine whether it has created a streams object, and return the UCXSTREAMS handle by calling UcxEndpointGetStaticStreamsReferenced.

After the object is created, the driver creates a framework queue object for each stream and sends the WDFQUEUE handle to UCX by calling UcxStaticStreamsSetStreamInfo.

The stream object provides several callback functions for the host controller to assist UCX with managing the static streams.

EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE
Release controller resources for all streams for an endpoint.

EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE
Enable controller hardware of all streams for this endpoint.

The lifetime of the object and associated queues are managed by UCX, and the driver must not delete the objects.